Windows Procedures

Assorted Windows procedures.

Include File: AfxWin.inc.

Window

Messages

Handles

Window styles

Display

Dialogs

High DPI

Fonts

Clipboard

Bitmap

Device Independent Bitmap (DIB)

Metric conversions

Mail and Internet

Miscellaneous procedures

Versioning

AfxWindowsVersion

Returns the Windows version.

FUNCTION AfxWindowsVersion () AS LONG

Return value

Platform 1:

  400 Windows 95
  410 Windows 98
  490 Windows ME

Platform 2:

  400 Windows NT
  500 Windows 2000
  501 Windows XP
  502 Windows Server 2003
  600 Windows Vista and Windows Server 2008
  601 Windows 7
  602 Windows 8
  603 Windows 8.1
 1000 Windows 10

Note: As Windows 95 and Windows NT return the same version number, we also need to call GetWindowsPlatform to differentiate them.

AfxWindowsBuild

Returns the Windows build number.

FUNCTION AfxWindowsBuild () AS LONG

AfxWindowsPlatform

Returns the Windows platform.

FUNCTION AfxWindowsPlatform () AS LONG

Return value

AfxWindowsBitness

Returns the Windows bitness (32 or 64 bit).

FUNCTION AfxWindowsBitness () AS LONG

AfxIsPlatformNT

Returns TRUE if the Windows Platform is NT; FALSE, otherwise.

FUNCTION AfxIsPlatformNT () AS BOOLEAN

AfxComCtlVersion

Returns the version of CommCtl32.dll

FUNCTION AfxComCtlVersion () AS LONG

Return value

The version of CommCtl32.dll multiplied by 100, e.g. 582 for version 5.82.

AfxMsg

Displays an application modal message box. Helper proceudre to display feedback and errors.

FUNCTION AfxMsg (BYVAL pwszText AS WSTRING PTR, BYREF wszCaption AS WSTRING = "Message", _
   BYVAL uType AS DWORD = 0) AS LONG
FUNCTION AfxMsg (BYREF cws AS CWSTR, BYREF wszCaption AS WSTRING = "Message", _
   BYVAL uType AS DWORD = 0) AS LONG
FUNCTION AfxMsg (BYREF cbs AS CBSTR, BYREF wszCaption AS WSTRING = "Message", _
   BYVAL uType AS DWORD = 0) AS LONG
FUNCTION AfxMsg (BYREF cv AS CVAR, BYREF wszCaption AS WSTRING = "Message", _
   BYVAL uType AS DWORD = 0) AS LONG
FUNCTION AfxMsg (BYVAL nValue AS DOUBLE, BYREF wszCaption AS WSTRING = "Message", _
   BYVAL uType AS DWORD = 0) AS LONG

Return value

The version of CommCtl32.dll multiplied by 100, e.g. 582 for version 5.82.

AfxGetWinErrMsg

Retrieves the localized description of the specified Windows error code.

FUNCTION AfxGetWinErrMsg (BYVAL dwError AS DWORD) AS CWSTR

Return value

The localized description of the error code.

AfxCommand

Returns command line parameters used to call the program.

FUNCTION AfxCommand (BYVAL nIndex AS LONG = -1) AS CWSTR

Return value

Returns the command-line arguments(s).

Remarks

AfxCommand returns command-line arguments passed to the program upon execution.

If index is less than zero (< 0), a space-separated list of all command-line arguments is returned, otherwise, a single argument is returned. A value of zero (0) returns the name of the executable; and values of one (1) and greater return each command-line argument.

If index is greater than the number of arguments passed to the program, a null string ("") is returned.

AfxEnviron

Retrieves the contents of the specified variable from the environment block of the calling process.

FUNCTION AfxEnviron (BYVAL pwszName AS LPCWSTR) AS CWSTR

Include file: AfxStr.inc

Usage example

DIM cws AS CWSTR = AfxEnviron("path")

AfxSetEnviron

Sets the contents of the specified environment variable for the current process.

FUNCTION AfxSetEnviron (BYVAL pwszName AS LPCWSTR, BYVAL pwszValue AS LPCWSTR) AS BOOLEAN

Include file: AfxStr.inc

Return value

If the function succeeds, the return value is TRUE.
If the function fails, the return value is FALSE.
To get extended error information, call GetLastError.

Usage example

AfxSetEnviron("path", "c:")

AfxSetEnviron (Overload)

Sets the contents of the specified environment variable for the current process.
Unicode replacement for Free Basic's SetEnviron function.

FUNCTION AfxSetEnviron (BYVAL pwszName AS LPCWSTR, BYVAL pwszValue AS LPCWSTR) AS BOOLEAN
FUNCTION AfxSetEnviron (BYREF varexp AS WSTRING) AS BOOLEAN

Include file: AfxStr.inc

Return value

Returns 0 on success, or -1 on failure.

AfxSetDlgMsgResult

Sets the return value of a message processed in the dialog box procedure.

FUNCTION AfxSetDlgMsgResult (BYVAL hDlg AS HWND, BYVAL msg AS UINT, BYVAL result AS LONG) AS BOOLEAN

Return value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

AfxExtractResource

Extracts resource data and returns it as a string.

FUNCTION AfxExtractResource (BYVAL hInstance AS HINSTANCE, _
   BYREF wszResourceName AS WSTRING, BYVAL pResourceType AS LPWSTR = MAKEINTRESOURCEW(10)) AS STRING

Return value

A string containing the resource data.

Example

DIM strResData AS STRING = AfxExtractResource(NULL, "IDI_ARROW_RIGHT")
where IDI_ARROW_RIGHT is the identifier in the resource file for
IDI_ARROW_RIGHT RCDATA ".\Resources\arrow_right_64.png"
--or--
DIM strResData AS STRING = AfxExtractResource(NULL, "#111")
' where "#111" is the identifier in the resource file for
' 111 RCDATA ".\Resources\VEGA_PAZ_01.jpg"
-----
' // Write the resource data to a file
DIM hFile AS HANDLE = CreateFileW("PazVega.jpg", GENERIC_WRITE, 0, NULL, CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL, NULL)
IF hFile THEN
   DIM dwBytesWritten AS DWORD
   DIM bSuccess AS BOOLEAN = WriteFile(hFile, STRPTR(strResData), LEN(strResData), @dwBytesWritten, NULL)
   CloseHandle(hFile)
   print bSuccess
END IF

AfxExtractResourceToFile

Extracts resource data and saves it to a file.

FUNCTION AfxExtractResourceToFile (BYVAL hInstance AS HINSTANCE, BYREF wszResourceName AS WSTRING, _
   BYREF wszFileName AS WSTRING, BYVAL pResourceType AS LPWSTR = MAKEINTRESOURCEW(10)) AS STRING

Return value

TRUE on success of FALSE on failure.

Example

AfxExtractResourceToFile(NULL, "IDI_ARROW_RIGHT", "IDI_ARROW_RIGHT.png")
where IDI_ARROW_RIGHT is the identifier in the resource file for
IDI_ARROW_RIGHT RCDATA ".\Resources\arrow_right_64.png"

Example

AfxExtractResourceToFile(NULL, "#111", "VEGA_PAZ_01.jpg")
where "#111" is the identifier in the resource file for
111 RCDATA ".\Resources\VEGA_PAZ_01.jpg"

AfxGetComputerName

Retrieves the NetBIOS name of the local computer. This name is established at system startup, when the system reads it from the registry.

FUNCTION AfxGetComputerName () AS CWSTR

Return value

The NetBIOS name of the local computer.

Remarks

The behavior of this function can be affected if the local computer is a node in a cluster. For more information, see ResUtilGetEnvironmentWithNetName and UseNetworkName.

AfxGetUserName

Retrieves the name of the user associated with the current thread.

FUNCTION AfxGetUserName () AS CWSTR

Return value

The name of the current user associated with the current thread.

Remarks

If the current thread is impersonating another client, the AfxGetUserName function returns the user name of the client that the thread is impersonating.

AfxGetMACAddress

Retrieves the MAC address of a machine's Ethernet card.

FUNCTION AfxGetMACAddress () AS STRING

Return value

The MAC address in the following format: MM-MM-MM-SS-SS-SS. The leftmost 6 digits, called a "prefix", is associated with the adapter manufacturer. The rightmost digits of a MAC address represent an identification number for the specific device.

Remarks

This function only supports one NIC card on your PC.

AfxDoEvents

Processes pending Windows messages. Call this procedure if you are performing a tight FOR/NEXT or DO/LOOP and need to allow your application to be responsive to user input.

SUB AfxDoEvents (BYVAL hwnd AS HWND = NULL)

AfxPumpMessages

Processes pending Windows messages. Call this procedure if you are performing a tight FOR/NEXT or DO/LOOP and need to allow your application to be responsive to user input.

SUB AfxPumpMessages

AfxForwardSizeMessage

Sends a WM_SIZE message to the specified window.

FUNCTION AfxForwardSizeMessage (BYVAL hwnd AS HWND, BYVAL nResizeType AS DWORD, _
   BYVAL nWidth AS LONG, BYVAL nHeight AS LONG) AS LRESULT

Remark

If an application processes this message, it should return zero.

AfxChooseColorDialog

Displays the Windows choose color dialog.

FUNCTION AfxChooseColorDialog (BYVAL hwnd AS HWND, BYVAL rgbDefaultColor AS COLORREF = 0, _
   BYVAL lpCustColors AS COLORREF PTR = NULL) AS LONG

Return value

The selected color, or -1 if the user has canceled the dialog.

AfxControlRunDLL

Control_RunDLL is an undocumented procedure in the Shell32.dll which can be used to launch control panel applications. You’ve to pass the name of the control panel file (.cpl) and the tool represented by it will be launched. For launching some control panel applications, you’ve to provide a valid windows handle (hwnd parameter) and program instance (hInst) parameter).

FUNCTION AfxControlRunDLL (BYVAL hwnd AS HWND, BYVAL hInst AS HINSTANCE, _
   BYVAL cmd AS WSTRING PTR, BYVAL nCmdShow AS LONG) AS BOOLEAN

Usage examples

AfxControlRunDLL(0, 0, "", SW_SHOWNORMAL)   ' Opens the control panel
AfxControlRunDLL(0, 0, "appwiz.cpl", SW_SHOWNORMAL)   ' Opens the applications wizard

AfxShowSysInfo

Displays the Windows Information System dialog.

FUNCTION AfxShowSysInfo (BYVAL hwnd AS HWND) AS BOOLEAN

Return value

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE.

AfxGetBrowserHandle

Retrieves the handle of the top level window of the web browser.

FUNCTION AfxGetBrowserHandle (BYVAL pwszClassName AS WSTRING PTR) AS HWND
FUNCTION AfxGetInternetExplorerHandle () AS HWND
FUNCTION AfxGetFireFoxHandle () AS HWND
FUNCTION AfxGetGoogleChromeHandle () AS HWND

Return value

The handle of the top level window of the browser. If there is not any instance of the browser running, it will return NULL.

Examples

DIM hwndBrowser AS HWND = AfxGetBrowserHandle("IEFrame")              ' // Internet Explorer
DIM hwndBrowser AS HWND = AfxGetBrowserHandle("MozillaWindowClass")   ' // Firefox
DIM hwndBrowser AS HWND = AfxGetBrowserHandle("Chrome_WidgetWin_1")   ' // Chrome

Remarks

AfxGetInternetExplorerHandle, AfxGetFireFoxHandle and AfxGetGoogleChromeHandle are wrappers functions that call AfxGetBrowserHandle passing the appropriate class name ("IEFrame", "MozillaWindowClass" and "Chrome_WidgetWin_1").

AfxGetDefaultBrowserName

Retrieves the name of the default browser.

FUNCTION AfxGetDefaultBrowserName () AS CWSTR

Return value

The retrieved name or an empty string.

AfxGetDefaultBrowserPath

Retrieves the path of the default browser.

FUNCTION AfxGetDefaultBrowserPath () AS CWSTR

Return value

The retrieved path or an empty string.

AfxGetDefaultMailClientName

Retrieves the name of the default client mail application.

FUNCTION AfxGetDefaultMailClientName () AS CWSTR

Return value

The retrieved name or an empty string.

AfxGetDefaultMailClientPath

Retrieves the path of the default client mail application.

FUNCTION AfxGetDefaultMailClientPath () AS CWSTR

Return value

The retrieved path or an empty string.

AfxGetInternetExplorerVersion

Returns the Internet Explorer version installed.

FUNCTION AfxGetInternetExplorerVersion () AS SINGLE

Return value

The Internet Explorer version (major.minor).

AfxHiMetricToPixelsX

Converts from HiMetric to Pixels (horizontal resolution). Himetric is a scaling unit similar to twips used in computing. It is one thousandth of a centimeter and is independent of the screen resolution. HiMetric per inch = 2540; 1 inch = 2.54 mm.

SUB AfxHiMetricToPixelsX (BYVAL hm AS LONG) AS LONG

Return value

The size in pixels.

AfxHiMetricToPixelsY

Converts from HiMetric to Pixels (vertical resolution). Himetric is a scaling unit similar to twips used in computing. It is one thousandth of a centimeter and is independent of the screen resolution. HiMetric per inch = 2540; 1 inch = 2.54 mm.

SUB AfxHiMetricToPixelsY (BYVAL hm AS LONG) AS LONG

Return value

The size in pixels.

AfxPixelsToHiMetricX

Converts from Pixels to HiMetric (horizontal resolution). Himetric is a scaling unit similar to twips used in computing. It is one thousandth of a centimeter and is independent of the screen resolution. HiMetric per inch = 2540; 1 inch = 2.54 mm.

SUB AfxPixelsToHiMetricX (BYVAL cx AS LONG) AS LONG

Return value

The size in HiMetric units.

AfxPixelsToHiMetricY

Converts from Pixels to HiMetric (vertical resolution). Himetric is a scaling unit similar to twips used in computing. It is one thousandth of a centimeter and is independent of the screen resolution. HiMetric per inch = 2540; 1 inch = 2.54 mm.

SUB AfxPixelsToHiMetricY (BYVAL cx AS LONG) AS LONG

Return value

The size in HiMetric units.

AfxPixelsToPointsX

Converts pixels to points size (1/72 of an inch). Horizontal resolution.

SUB AfxPixelsToPointsX (BYVAL pix AS LONG) AS LONG

Return value

The number of points.

AfxPixelsToPointsY

Converts pixels to points size (1/72 of an inch). Vertical resolution.

SUB AfxPixelsToPointsY (BYVAL pix AS LONG) AS LONG

Return value

The number of points.

AfxPixelsToTwipsX

Converts pixels to twips. Horizontal resolution.

FUNCTION AfxPixelsToTwipsX (BYVAL nPixels AS LONG) AS LONG

Return value

The number of twips.

AfxPixelsToTwipsY

Converts pixels to twips. Vertical resolution.

FUNCTION AfxPixelsToTwipsY (BYVAL nPixels AS LONG) AS LONG

Return value

The number of twips.

AfxPointSizeToDip

Converts point size to DIP (device independent pixel). DIP is defined as 1/96 of an inch and a point is 1/72 of an inch.

FUNCTION AfxPointSizeToDip (BYVAL ptsize AS SINGLE) AS SINGLE

Return value

The number of DIP pixels.

AfxPointsToPixelsX

Converts a point size (1/72 of an inch) to pixels. Horizontal resolution.

FUNCTION AfxPointsToPixelsX (BYVAL pts AS LONG) AS LONG

Return value

The number of pixels.

AfxPointsToPixelsY

Converts a point size (1/72 of an inch) to pixels. Vertical resolution.

FUNCTION AfxPointsToPixelsY (BYVAL pts AS LONG) AS LONG

Return value

The number of pixels.

AfxTwipsPerPixelX

Returns the width of a pixel in twips (horizontal resolution). Pixel dimensions can vary between systems and may not always be square, so separate functions for pixel width and height are required.

FUNCTION AfxTwipsPerPixelX () AS LONG

Return value

The number of twips per pixel.

AfxTwipsPerPixelY

Returns the width of a pixel in twips (vertical resolution). Pixel dimensions can vary between systems and may not always be square, so separate functions for pixel width and height are required.

FUNCTION AfxTwipsPerPixelY () AS LONG

Return value

The number of twips per pixel.

AfxTwipsToPixelsX

Converts twips to pixels. Horizontal resolution.

FUNCTION AfxTwipsToPixelsX (BYVAL nTwips AS LONG) AS LONG

Return value

The number of pixels.

AfxTwipsToPixelsY

Converts twips to pixels. Vertical resolution.

FUNCTION AfxTwipsToPixelsY (BYVAL nTwips AS LONG) AS LONG

Return value

The number of pixels.

AfxCaptureDisplay

Captures the display and returns an handle to a bitmap.

FUNCTION AfxCaptureDisplay () AS HBITMAP

Return value

The handle of a bitmap.

Usage example

DIM hBitmap AS HBITMAP = AfxCaptureDisplay

AfxGetBitmapHeight

Retrieves the height of the specified bitmap.

FUNCTION AfxGetBitmapHeight (BYVAL hBitmap AS HBITMAP) AS LONG

Return value

The height of the bitmap on success or 0 on failure.

AfxGetBitmapWidth

Retrieves the width of the specified bitmap.

FUNCTION AfxGetBitmapWidth (BYVAL hBitmap AS HBITMAP) AS LONG

Return value

The width of the bitmap on success or 0 on failure.

AfxCreateDIBSection

Creates a DIB section.

FUNCTION AfxCreateDIBSection (BYVAL hdc AS HDC, BYVAL nWidth AS DWORD, BYVAL nHeight AS DWORD, _
   BYVAL bpp AS LONG = 0, BYVAL ppvBits AS ANY PTR PTR = NULL) AS HBITMAP

Return value

If the function succeeds, the return value is a handle to the newly created DIB, and ppvBits points to the bitmap bit values.

If the function fails, the return value is NULL, and ppvBits is NULL. The function can fail if one or more of the input parameters is invalid.

This function can return the following value: ERROR_INVALID_PARAMETER (One or more of the input parameters is invalid).

Remarks

You must delete the returned bitmap handle with DeleteObject when no longer needed to avoid memory leaks.

You cannot paste a DIB section from one application into another application.

AfxCreateDIBSection does not use the BITMAPINFOHEADER parameters biXPelsPerMeter or biYPelsPerMeter and will not provide resolution information in the BITMAPINFO structure.

Usage example

DIM hdcWindow AS HDC, hbmp AS HBITMAP, pvBits AS ANY PTR
hdcWindow = GetWindowDC(hwnd)   ' where hwnd is the handle of the wanted window or control
hbmp = AfxCreateDIBSection(hdcWindow, 10, 10, @pvBits)
ReleaseDC(hwnd, hdcWindow)

AfxDibLoadImage

Loads a DIB in memory and returns a pointer to it.

FUNCTION AfxDibLoadImage (BYVAL pwszFileName AS WSTRING PTR) AS BITMAPFILEHEADER PTR

Return value

A pointer to the bitmap file header. You must release it with CoTaskMemFree when no longer needed.

AfxDibSaveImage

Saves a DIB to a file.

FUNCTION AfxDibSaveImage (BYVAL pwszFileName AS WSTRING PTR, BYVAL pbmfh AS BITMAPFILEHEADER PTR) AS BOOLEAN

Return value

TRUE if the DIB has been saved successfully; FALSE otherwise.

AfxClearClipboard

Clears the contents of the clipboard.

FUNCTION AfxClearClipboard () AS LONG

Return value

If the function succeeds, the return value is nonzero. If the function fails, the return value is zero.

AfxGetClipboardData

Retrieves data from the clipboard in the specified format.

FUNCTION AfxGetClipboardData (BYVAL cfFormat AS DWORD) AS HGLOBAL

Standard clipboard formats:

Return value

If the function succeeds, the return value is the handle to the data. If the function fails, the return value is NULL.

AfxGetClipboardText

Returns a text string from the clipboard.

FUNCTION AfxGetClipboardText () AS CWSTR

Return value

The retrieved text string.

AfxSetClipboardData

Places data on the clipboard in a specified clipboard format.

FUNCTION AfxSetClipboardData (BYVAL cfFormat AS DWORD, BYVAL hData AS HANDLE) AS HANDLE

Standard clipboard formats:

Return value

If the function succeeds, the return value is the handle to the data. If the function fails, the return value is NULL.

Remarks

If AfxSetClipboardData succeeds, the system owns the object identified by the hData parameter. The application may not write to or free the data once ownership has been transferred to the system.

AfxSetClipboardText

Places a text string into the clipboard.

FUNCTION AfxSetClipboardText (BYREF wszText AS WSTRING) AS HANDLE

Return value

If the function succeeds, the return value is the handle to the data. If the function fails, the return value is NULL.

AfxCreateFont

Creates a logical font.

FUNCTION AfxCreateFont (BYREF wszFaceName AS WSTRING, BYVAL lPointSize AS LONG, BYVAL DPI AS LONG = 96, _
   BYVAL lWeight AS LONG = 0, BYVAL bItalic AS UBYTE = FALSE, BYVAL bUnderline AS UBYTE = FALSE, _
   BYVAL bStrikeOut AS UBYTE = FALSE, BYVAL bCharSet AS UBYTE = DEFAULT_CHARSET) AS HFONT

Return value

The handle of the font or NULL on failure.

Remarks

The returned font must be destroyed with DeleteObject or the macro DeleteFont when no longer needed to prevent memory leaks.

Usage examples

hFont = AfxCreateFont("MS Sans Serif", 8, , FW_NORMAL, , , , DEFAULT_CHARSET)
hFont = AfxCreateFont("Courier New", 10, 96 , FW_BOLD, , , , DEFAULT_CHARSET)
hFont = AfxCreateFont("Marlett", 8, -1, FW_NORMAL, , , , SYMBOL_CHARSET)

AfxGetFontHeight

Returns the logical height of a font given its point size.

FUNCTION AfxGetFontHeight (BYVAL nPointSize AS LONG) AS LONG

AfxGetFontPointSize

Returns the point size of a font given its logical height.

FUNCTION AfxGetFontPointSize (BYVAL nHeight AS LONG) AS LONG

AfxGetWindowFont

Retrieves the font with which the window or control is currently drawing its text.

FUNCTION AfxGetWindowFont (BYVAL hwnd AS HWND) AS HFONT

Return value

The handle of the font.

AfxGetWindowFontInfo

Retrieves information about the font being used by a window or control.

FUNCTION AfxGetWindowFontInfo (BYVAL hwnd AS HWND) AS LOGFONTW

Return value

A LOGFONTW structure.

AfxGetWindowsFontInfo

Retrieves information about the fonts used by Windows.

FUNCTION AfxGetWindowsFontInfo (BYVAL nType AS LONG, BYVAL plfw AS LOGFONTW PTR) AS BOOLEAN

Return value

TRUE on succes or FALSE on failure. To get extended error information, call GetLastError.

AfxGetWindowsFontPointSize

Retrieves the point size of the fonts used by Windows.

FUNCTION AfxGetWindowsFontPointSize (BYVAL nType AS LONG) AS LONG

AfxModifyFontFaceName

Modifies the face name of the font of a window or control.

FUNCTION AfxModifyFontFaceName (BYVAL hwnd AS HWND, BYREF wszNewFaceName AS WSTRING) AS HFONT

Return value

The handle of the new font on success, or NULL on failure.

To get extended error information call GetLastError.

Remarks

The returned font must be destroyed with DeleteObject or the macro DeleteFont when no longer needed to prevent memory leaks.

AfxModifyFontHeight

Modifies the height of the font used by a window of control.

FUNCTION AfxModifyFontHeight (BYVAL hwnd AS HWND, BYVAL nValue AS LONG) AS HFONT

Return value

The handle of the new font on success, or NULL on failure.

To get extended error information call GetLastError.

Remarks

The returned font must be destroyed with DeleteObject or the macro DeleteFont when no longer needed to prevent memory leaks.

AfxModifyFontSettings

Modifies settings of the font used by a window of control.

FUNCTION AfxModifyFontSettings (BYVAL hwnd AS HWND, BYVAL nSetting AS LONG, BYVAL nValue AS LONG) AS HFONT

Return value

The handle of the new font on success, or NULL on failure.

To get extended error information call GetLastError.

Remarks

The returned font must be destroyed with DeleteObject or the macro DeleteFont when no longer needed to prevent memory leaks.

AfxSetWindowFont

Sets the font that a control is to use when drawing text.

SUB AfxSetWindowFont (BYVAL hwnd AS HWND, BYVAL hFont AS HFONT, BYVAL fRedraw AS LONG = CTRUE)

Return value

The handle of the new font on success, or NULL on failure.

To get extended error information call GetLastError.

Remarks

The application should call the DeleteObject function to delete the font when it is no longer needed; for example, after it destroys the control.

The size of the control does not change as a result of receiving this message. To avoid clipping text that does not fit within the boundaries of the control, the application should correct the size of the control window before it sets the font.

AfxForceVisibleDisplay

If you use dual (or even triple/quad) displays then you have undoubtedly encountered the following situation: You change the physical order of your displays, or otherwise reconfigure the logical ordering using your display software. This sometimes has the side-effect of changing your desktop coordinates from zero-based to negative starting coordinates (i.e. the top-left coordinate of your desktop changes from 0,0 to -1024,-768).

This effects many Windows programs which restore their last on-screen position whenever they are started. Should the user reorder their display configuration this can sometimes result in a Windows program subsequently starting in an off-screen position (i.e. at a location that used to be visible) - and is now effectively invisible, preventing the user from closing it down or otherwise moving it back on-screen.

The AfxForceVisibleDisplay function can be called at program start-time right after the main window has been created and positioned 'on-screen'. Should the window be positioned in an off-screen position, it is forced back onto the nearest display to its last position. The user will be unaware this is happening and won't even realize to thank you for keeping their user-interface visible, even though they changed their display settings.

Source: Catch-22 web site.

SUB AfxForceVisibleDisplay (BYVAL hwnd AS HWND)

AfxGetDisplayBitsPerPixel

Returns the color resolution, in bits per pixel, of the display device.

FUNCTION AfxGetDisplayBitsPerPixel () AS DWORD

AfxGetDisplayFrequency

Returns the frequency, in hertz (cycles per second), of the display device in a particular mode. This value is also known as the display device's vertical refresh rate.

FUNCTION AfxGetDisplayBitsPerPixel () AS DWORD

AfxGetDisplayPixelsHeight

Returns the height, in pixels, of the current display device on the computer on which the calling thread is running.

FUNCTION AfxGetDisplayPixelsHeight () AS DWORD

AfxGetDisplayPixelsWidth

Returns the width, in pixels, of the current display device on the computer on which the calling thread is running.

FUNCTION AfxGetDisplayPixelsWidth () AS DWORD

Remarks

Contrarily to GetSystemMetrics or GetDeviceCaps, it returns the real width even when it is called from an application that is not DPI aware, e.g. an application running virtualized in a monitor 1920 pixels width and a DPI of 192, will return 960 pixels if it calls GetSystemMetrics or GetDeviceCaps, but will return 1920 pixels calling AfxGetDisplayPixelsWidth.

AfxLogPixelsX / AfxGetDpi / AfxGetDpiX

Retrieves the number of pixels per logical inch along the screen width. In a system with multiple display monitors, this value is the same for all monitors.

FUNCTION AfxLogPixelsX () AS LONG
FUNCTION AfxGetDpi () AS LONG
FUNCTION AfxGetDpiX () AS LONG

AfxLogPixelsX / AfxGetDpiY

Retrieves the number of pixels per logical inch along the screen height. In a system with multiple display monitors, this value is the same for all monitors.

FUNCTION AfxLogPixelsY () AS LONG
FUNCTION AfxGetDpiY () AS LONG

AfxGetMonitorHorizontalScaling

Returns the horizontal scaling of the monitor that the window is currently displayed on.

FUNCTION AfxGetMonitorHorizontalScaling (BYVAL hwnd AS HWND = NULL) AS DWORD

Remarks

If the application to which the window belongs is not DPI aware, a computer using 192 DPI, will return an scaling ratio of 2.

AfxGetMonitorVerticalScaling

Returns the vertical scaling of the monitor that the window is currently displayed on.

FUNCTION AfxGetMonitorVerticalScaling (BYVAL hwnd AS HWND = NULL) AS DWORD

Remarks

If the application to which the window belongs is not DPI aware, a computer using 192 DPI, will return an scaling ratio of 2.

AfxGetMonitorLogicalHeight

Returns the logical height of the monitor that the window is currently displayed on.

FUNCTION AfxGetMonitorLogicalHeight (BYVAL hwnd AS HWND = NULL) AS DWORD

Remarks

If the application to which the window belongs is not DPI aware, a monitor with an height resolution of 1080 pixels in a computer using 192 DPI, will return 540 pixels.

AfxGetMonitorLogicalWidth

Returns the logical width of the monitor that the window is currently displayed on.

FUNCTION AfxGetMonitorLogicalWidth (BYVAL hwnd AS HWND = NULL) AS DWORD

Remarks

If the application to which the window belongs is not DPI aware, a monitor with a width resolution of 1920 pixels in a computer using 192 DPI, will return 960 pixels.

AfxIsDPIResolutionAtLeast

Determines if screen resolution meets minimum requirements in relative pixels, e.g. for a screen resolution of 1920x1080 pixels and a DPI of 192 (scaling ratio = 2), the maximum relative pixels for a DPI aware application is 960x540.

FUNCTION AfxIsDPIResolutionAtLeast (BYVAL cxMin AS LONG, BYVAL cyMin AS LONG) AS BOOLEAN

Return value

TRUE or FALSE.

AfxIsResolutionAtLeast

Determines if screen resolution meets minimum requirements.

FUNCTION AfxIsResolutionAtLeast (BYVAL cxMin AS LONG, BYVAL cyMin AS LONG) AS BOOLEAN

Return value

TRUE or FALSE.

AfxSetProcessDPIAware

Sets the current process as dots per inch (dpi) aware.

Note: AfxSetProcessDPIAware is subject to a possible race condition if a DLL caches dpi settings during initialization. For this reason, it is recommended that dpi-aware be set through the application (.exe) manifest rather than by calling AfxSetProcessDPIAware.

FUNCTION AfxSetProcessDPIAware () AS BOOLEAN

Return value

If the function succeeds, the return value is TRUE. Otherwise, the return value is FALSE.

Remarks

DLLs should accept the dpi setting of the host process rather than call AfxSetProcessDPIAware themselves. To be set properly, dpiAware should be specified as part of the application (.exe) manifest. (dpiAware defined in an embedded DLL manifest has no affect.) The following markup shows how to set dpiAware as part of an application (.exe) manifest.

<assembly xmlns="urn:schemas-microsoft-com:asm.v1" manifestVersion="1.0" xmlns:asmv3="urn:schemas-microsoft-com:asm.v3" >
 ...
  <asmv3:application>
    <asmv3:windowsSettings xmlns="http://schemas.microsoft.com/SMI/2005/WindowsSettings">
      <dpiAware>true</dpiAware>
    </asmv3:windowsSettings>
  </asmv3:application>
 ...
</assembly>

AfxIsProcessDPIAware

Determines whether the current process is dots per inch (dpi) aware such that it adjusts the sizes of UI elements to compensate for the dpi setting.

FUNCTION AfxIsProcessDPIAware () AS BOOLEAN

Return value

TRUE if the process is dpi aware; otherwise, FALSE.

AfxLoadIconMetric

Loads a specified icon resource with a client-specified system metric.

FUNCTION AfxLoadIconMetric (BYVAL hinst AS HINSTANCE, BYVAL pwszName AS WSTRING PTR, _
   BYVAL lims AS LONG, BYVAL phico AS HICON PTR) AS HRESULT

Return value

Returns S_OK if successful, otherwise an error, including the following value: E_INVALIDARG : The contents of the buffer pointed to by pszName do not fit any of the expected interpretations.

Remarks

LoadIconMetric is similar to LoadIcon, but with the capability to specify the icon metric. It is used in place of LoadIcon when the calling application wants to ensure a high quality icon. This is particularly useful in high dots per inch (dpi) situations.

Icons are extracted or created as follows.

1. If an exact size match is found in the resource, that icon is used.
   
2. If an exact size match cannot be found and a larger icon is available, a new icon is created by scaling the larger version down to the desired size.
   
3. If an exact size match cannot be found and no larger icon is available, a new icon is created by scaling a smaller icon up to the desired size.

AfxScaleRatioX

Retrieves the desktop horizontal scaling ratio.

FUNCTION AfxScaleRatioX () AS LONG

AfxScaleRatioY

Retrieves the desktop vertical scaling ratio.

FUNCTION AfxScaleRatioY () AS LONG

AfxScaleX

Scales an horizontal coordinate according the DPI (dots per pixel) being used by the operating system.

FUNCTION AfxScaleX (BYVAL cx AS SINGLE) AS SINGLE

Return value

The scaled coordinate.

AfxScaleY

Scales a vertical coordinate according the DPI (dots per pixel) being used by the operating system.

FUNCTION AfxScaleY (BYVAL cx AS SINGLE) AS SINGLE

Return value

The scaled coordinate.

AfxUnscaleX

Unscales an horizontal coordinate according the DPI (dots per pixel) being used by the operating system.

FUNCTION AfxUnscaleX (BYVAL cx AS SINGLE) AS SINGLE

Return value

The unscaled coordinate.

AfxUnscaleY

Unscales a vertical coordinate according the DPI (dots per pixel) being used by the operating system.

FUNCTION AfxUnscaleY (BYVAL cx AS SINGLE) AS SINGLE

Return value

The unscaled coordinate.

AfxUseDpiScaling

Returns TRUE if the OS uses DPI scaling; FALSE otherwise.

FUNCTION AfxUseDpiScaling () AS BOOLEAN

AfxAddWindowExStyle

Adds a new extended style to the specified window.

FUNCTION AfxAddWindowExStyle (BYVAL hwnd AS HWND, BYVAL dwExStyle AS DWORD) AS DWORD

Return value

The previous window extended styles.

Usage example

AfxAddWindowExStyle(hwnd, WS_EX_COMPOSITED)

Remarks

If the window has a class style of CS_CLASSDC or CS_OWNDC, do not set the extended window styles WS_EX_COMPOSITED or WS_EX_LAYERED.

AfxAddWindowStyle

Adds a new style to the specified window.

FUNCTION AfxAddWindowStyle (BYVAL hwnd AS HWND, BYVAL dwStyle AS DWORD) AS DWORD

Return value

The previous window styles.

Usage example

AfxAddWindowStyle(hwnd, WS_HSCROLL)

AfxGetWindowExStyle

Retrieves the extended window styles.

FUNCTION AfxGetWindowExStyle (BYVAL hwnd AS HWND) AS DWORD

AfxGetWindowStyle

Retrieves the window styles.

FUNCTION AfxGetWindowStyle (BYVAL hwnd AS HWND) AS DWORD

AfxRemoveWindowExStyle

Removes an extended style from the specified window.

FUNCTION AfxRemoveWindowExStyle (BYVAL hwnd AS HWND, BYVAL dwExStyle AS DWORD) AS DWORD

Return value

The previous extended window styles.

AfxRemoveWindowStyle

Removes a style from the specified window.

FUNCTION AfxRemoveWindowStyle (BYVAL hwnd AS HWND, BYVAL dwStyle AS DWORD) AS DWORD

Return value

The previous window styles.

AfxSetWindowExStyle

Sets the extended style(s) of the specified window.

FUNCTION AfxSetWindowExStyle (BYVAL hwnd AS HWND, BYVAL dwExStyle AS DWORD) AS DWORD

Return value

The previous extended window styles.

AfxSetWindowStyle

Sets the style(s) of the specified window.

FUNCTION AfxSetWindowStyle (BYVAL hwnd AS HWND, BYVAL dwStyle AS DWORD) AS DWORD

Return value

The previous window styles.

AfxGetControlHandle

Returns the handle of the control with the specified identifier. The reference handle can be the handle of the form or the handle of any other control on the form.

FUNCTION AfxGetControlHandle (BYVAL hwnd AS HWND, BYVAL wCtrlID AS WORD) AS HWND

Return value

Returns the handle of the control or NULL.

AfxGetFormHandle

Finds the handle of the top-level window or MDI child window that is the ancestor of the specified window handle. The reference handle is the handle of any control on the form.

FUNCTION AfxGetFormHandle (BYVAL hwnd AS HWND) AS HWND

Return value

Handle of the ancestor window.

AfxGetHwndFromPID

Retrieves a window handle given it's process identifier.

FUNCTION AfxGetHwndFromPID (BYVAL PID AS DWORD) AS HWND

Return value

The window handle or NULL.

AfxGetPathFromWindowHandle

Retrieves the path of the executable file that created the specified window.

FUNCTION AfxGetPathFromWindowHandle (BYVAL hwnd AS HWND) AS CWSTR

Return value

The path of the executable file.

AfxCenterWindow

Centers a window on the screen or over another window. It also ensures that the placement is done within the work area.

SUB AfxCenterWindow (BYVAL hwnd AS HWND = NULL, BYVAL hwndParent AS HWND = NULL)

AfxForceSetForegroundWindow

Brings the thread that created the specified window into the foreground and activates the window. Keyboard input is directed to the window, and various visual cues are changed for the user. The system assigns a slightly higher priority to the thread that created the foreground window than it does to other threads.

SUB AfxForceSetForegroundWindow (BYVAL hwnd AS HWND)

Remarks

Replacement for the SetForegroundWindow API function, that sometimes fails.

Warning

Don't use it. Apparently, AttachThreadInput can lead to a deadlock. See: The dangers of attaching input queues

AfxGetTopEnabledWindow

Retrieves the handle of the enabled and visible window at the top of the z-order in an application.

FUNCTION AfxGetTopEnabledWindow () AS HWND

Return value

Handle of the window at top of z-order or NULL.

AfxGetTopLevelParent

Retrieves the window's top-level parent window.

FUNCTION AfxGetTopEnabledWindow () AS HWND

Return value

Handle of the top-level parent window.

AfxGetTopLevelWindow

Retrieves the window's top-level parent or owner window.

FUNCTION AfxGetTopLevelWindow (BYVAL hwnd AS HWND) AS HWND

Return value

Handle of the top-level parent or owner window.

AfxGetWindowClassName

Retrieves the name of the class to which the specified window belongs.

FUNCTION AfxGetWindowClassName (BYVAL hwnd AS HWND) AS CWSTR

Return value

The name of the class.

AfxGetWindowClientHeight

Returns the height of the client area of window, in pixels.

FUNCTION AfxGetWindowClientHeight (BYVAL hwnd AS HWND) AS LONG

AfxGetWindowClientRect

Retrieves the coordinates of a window's client area. The client coordinates specify the upper-left and lower-right corners of the client area. Because client coordinates are relative to the upper-left corner of a window's client area, the coordinates of the upper-left corner are (0,0).

FUNCTION AfxGetWindowClientRect (BYVAL hwnd AS HWND) AS RECT

Return value

A RECT structure with the retrieved coordinates of the window's client area.

AfxGetWindowClientWidth

Returns the width of the client area of a window, in pixels.

FUNCTION AfxGetWindowClientWidth (BYVAL hwnd AS HWND) AS LONG

AfxGetWindowHeight

Returns the height of a window, in pixels.

FUNCTION AfxGetWindowHeight (BYVAL hwnd AS HWND) AS LONG

AfxGetWindowWidth

Returns the width of a window, in pixels.

FUNCTION AfxGetWindowWidth (BYVAL hwnd AS HWND) AS LONG

AfxGetWindowLocation

Returns the location of the top left corner of the window, in pixels. The location is relative to the upper-left corner of the client area in the parent window.

SUB AfxGetWindowLocation (BYVAL hwnd AS HWND, BYREF nLeft AS LONG, BYREF nTop AS LONG)

AfxGetWindowRect

Retrieves the dimensions of the bounding rectangle of the specified window. The dimensions are given in screen coordinates that are relative to the upper-left corner of the screen.

FUNCTION AfxGetWindowRect (BYVAL hwnd AS HWND) AS RECT

Return value

A RECT structure with the retrieved dimensions.

AfxGetWindowSize

Gets the width and height of the specified window, in pixels.

FUNCTION AfxGetWindowSize (BYVAL hwnd AS HWND, BYVAL nWidth AS LONG, BYVAL nHeight AS LONG) AS BOOLEAN

AfxGetWindowText

Gets the text of a window. This function can also be used to retrieve the text of buttons, edit and static controls.

FUNCTION AfxGetWindowText (BYVAL hwnd AS HWND) AS CWSTR

Return value

The text of the window.

For an edit control, the text returned is the content of the edit control. For a combo box, the text is the content of the edit control (or static-text) portion of the combo box. For a button, the text is the button name. For other windows, the text is the window title. To retrieve the text of an item in a list box, an application can use the ListBox_GetText function.

Rich Edit: If the text to be copied exceeds 64K, use either the EM_STREAMOUT or EM_GETSELTEXT message.

Remarks

This function uses the WM_GETTEXT message because GetWindowText cannot retrieve the text of a window in another application.

Usage examples

DIM cwsText AS CWSTR = AfxGetWindowText(hwnd) MessageBoxW 0, cwsText, "", MB_OK

AfxGetWindowTextLength

Retrieves the length of the text of a window. This function can also be used to retrieve the length of the text of buttons, edit and static controls.

FUNCTION AfxGetWindowTextLength (BYVAL hwnd AS HWND) AS LONG

Return value

If the function succeeds, the return value is the length of the text in characters, not including the terminating null character.

If the function fails, the return value is zero.

For an edit control, the text returned is the content of the edit control. For a combo box, the text is the content of the edit control (or static-text) portion of the combo box. For a button, the text is the button name. For other windows, the text is the window title. To retrieve the text of an item in a list box, an application can use the ListBox_GetTextLength function.

AfxGetWindowTextLength sends a WM_GETTEXTLENGTH message. When the WM_GETTEXTLENGTH message is sent, the DefWindowProc function returns the length, in characters, of the text. Under certain conditions, the DefWindowProc function returns a value that is larger than the actual length of the text. This occurs with certain mixtures of ANSI and Unicode, and is due to the system allowing for the possible existence of double-byte character set (DBCS) characters within the text. The return value, however, will always be at least as large as the actual length of the text; you can thus always use it to guide buffer allocation. This behavior can occur when an application uses both ANSI functions and common dialogs, which use Unicode.

To obtain the exact length of the text, use the WM_GETTEXT, LB_GETTEXT, or CB_GETLBTEXT messages, or the GetWindowText function.

Sending a WM_GETTEXTLENGTH message to a non-text static control, such as a static bitmap or static icon control, does not return a string value. Instead, it returns zero.

AfxGetWorkAreaHeight

Retrieves the height of the work area on the primary display monitor expressed in virtual screen coordinates. The work area is the portion of the screen not obscured by the system taskbar or by application desktop toolbars. To get the work area of a monitor other than the primary display monitor, call the GetMonitorInfo function.

FUNCTION AfxGetWorkAreaHeight () AS LONG

AfxGetWorkAreaRect

Retrieves the coordinates of the work area on the primary display monitor expressed in virtual screen coordinates. The work area is the portion of the screen not obscured by the system taskbar or by application desktop toolbars. To get the work area of a monitor other than the primary display monitor, call the GetMonitorInfo function.

FUNCTION AfxGetWorkAreaRect () AS RECT

Return value

A RECT structure with the retrieved coordinates.

AfxGetWorkAreaWidth

Retrieves the width of the work area on the primary display monitor expressed in virtual screen coordinates. The work area is the portion of the screen not obscured by the system taskbar or by application desktop toolbars. To get the work area of a monitor other than the primary display monitor, call the GetMonitorInfo function.

FUNCTION AfxGetWorkAreaWidth () AS LONG

AfxRedrawNonClientArea

Redraws the non-client area of the specified window.

FUNCTION AfxRedrawNonClientArea (BYVAL hwnd AS HWND) AS BOOLEAN

Return value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

AfxRedrawWindow

Redraws the specified window.

SUB AfxRedrawWindow (BYVAL hwnd AS HWND)

AfxSetWindowClientSize

Adjusts the bounding rectangle of a window based on the desired size of the client area.

SUB AfxSetWindowClientSize (BYVAL hwnd AS HWND, BYVAL nWidth AS LONG, BYVAL nHeight AS LONG, _
   BYVAL rxRatio AS SINGLE = 1, BYVAL ryRatio AS SINGLE = 1)

AfxSetWindowIcon

Associates a new large icon with a window. The system displays the large icon in the ALT+TAB dialog box, and the small icon in the window caption.

FUNCTION AfxSetWindowIcon (BYVAL hwnd AS HWND, BYVAL nIconType AS LONG, BYVAL hIcon AS HICON) AS HICON

Return value

The return value is a handle to the previous large or small icon, depending on the value of nIconType. It is NULL if the window previously had no icon of the type indicated by nIconType.

AfxSetWindowLocation

Sets the location of the top left corner of the window, in pixels.The location is relative to the upper-left corner of the client area in the parent window.

FUNCTION AfxSetWindowLocation (BYVAL hwnd AS HWND, BYVAL nLeft AS LONG, BYVAL nTop AS LONG) AS BOOLEAN

Return value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE. To get extended error information, call GetLastError.

AfxSetWindowSize

Sets the size of the specified window, in pixels.

FUNCTION AfxSetWindowSize (BYVAL hwnd AS HWND, BYVAL nWidth AS LONG, BYVAL nHeight AS LONG) AS BOOLEAN

AfxSetWindowText

Sets the text of a window. This function can also be used to set the text of buttons, edit and static controls.

FUNCTION AfxSetWindowText (BYVAL hwnd AS HWND, BYVAL pwszText AS WSTRING PTR) AS BOOLEAN

Return value

If the function succeeds, the return value is TRUE.

If the function fails, the return value is FALSE.

AfxShowWindowState

Sets the specified window's show state.

FUNCTION AfxShowWindowState (BYVAL hwnd AS HWND, BYVAL nShowState AS LONG) AS BOOLEAN

Return value

If the window was previously visible, the return value is TRUE.

If the window was previously hidden, the return value is FALSE.

Remarks

To perform certain special effects when showing or hiding a window, use AnimateWindow.

The first time an application calls AfxShowWindowState, it should use the WinMain function's nCmdShow parameter as its nCmdShow parameter. Subsequent calls to AfxShowWindowState must use one of the values in the given list, instead of the one specified by the WinMain function's nCmdShow parameter.

As noted in the discussion of the nCmdShow parameter, the nCmdShow value is ignored in the first call to AfxShowWindowState if the program that launched the application specifies startup information in the structure. In this case, AfxShowWindowState uses the information specified in the STARTUPINFO structure to show the window. On subsequent calls, the application must call AfxShowWindowState with nCmdShow set to SW_SHOWDEFAULT to use the startup information provided by the program that launched the application. This behavior is designed for the following situations:

• Applications create their main window by calling CreateWindow with the WS_VISIBLE flag set.
• Applications create their main window by calling CreateWindow with the WS_VISIBLE flag cleared, and later call AfxShowWindowState with the SW_SHOW flag set to make it visible.